home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 003 / tcdbf.arc / DBF.DOC < prev    next >
Encoding:
Text File  |  1987-06-19  |  9.5 KB  |  174 lines
  1. dBASE III interface routines for C.
  2. Author Mark Sadler  June 19, 1987
  3.  
  4. The routines included here provide some tools for access to dBASE III
  5. database files by Turbo C, version 1.0, programs.  These routines are very
  6. rudimentary. There is no support for index files, no buffering of data
  7. (other than what TC provides), no support for memo files, etc.  The
  8. functions included in this package are:
  9.  
  10.       D_ADDREC   -   function to append record to dbf file
  11.       D_BLANK    -   function to blank a record
  12.       D_CLOSE    -   function to close a dbf file
  13.       D_CPYSTR   -   function to copy an existing dbf structure to a new file
  14.       D_GETFLD   -   function to fill a buffer with the contents of field N
  15.       D_GETREC   -   function to get the contents of record N
  16.       D_OPEN     -   function to open a dbf file
  17.       D_PUTFLD   -   function to fill a field with the contents of a buffer
  18.       D_PUTREC   -   function to write a record to a dbf file
  19.       DBF.H      -   header file that must be included in programs calling
  20.                      above functions
  21.       DBF.LIB    -   library file of above functions (Small Model)
  22.  
  23. A skeletal program might look like this:
  24.  
  25. #include "dbf.h"
  26.  
  27. main()
  28. {
  29.   struct DBF *d;                                /* define DBF pointer        */
  30.   long record = 1L;                             /* define record number      */
  31.   d = (struct DBF *)malloc(sizeof(struct DBF)); /* allocate memory for struct*/
  32.   strcpy(d->filename,"filename.dbf");           /* fill filename             */
  33.   d_open(d);                                    /* open filename             */
  34.   d_getrec(d,record);                           /* get record                */
  35.   ... modify record or use information, or whatever ...
  36.   d_putrec(d,record);                           /* rewrite changed record    */
  37.   d_close(d);                                   /* close file                */
  38.   free(d);                                      /* release memory allocation */
  39. }
  40.  
  41. The d_open function takes a pointer to a DBF structure as an argument, with
  42. the filename field filled in.  The function then opens the file for
  43. read/write and fills the DBF structure with information about the file such
  44. as number of records, length of records, number of fields, etc.  d_open
  45. also allocates space for and fills an array of information about each
  46. field: size, name, type, etc. Finally, d_open allocates space in memory for
  47. a record to be held in memory and places memory location information for
  48. each field into the field array.  The pointers to the field array and
  49. record are included in the DBF structure.
  50.  
  51. The d_getrec function gets a record from the dbf file and places it in
  52. memory. while the record is in memory it may be accessed with the
  53. DBF.record_ptr.  If changes are made they may be written back to the dbf
  54. file with the d_putrec function.
  55.  
  56. The d_getfld function fills a buffer with the data within a field from a
  57. record that has been loaded into memory with d_getrec.  In other words this
  58. function extracts the data from a record in memory and converts it from
  59. dBASE III format to one that may be more easily accessed with a C
  60. program(i.e. zero terminated ascii).  d_putfld moves data from a buffer
  61. back into a record field.  Note that these functions do not get the record
  62. that contains the field.  This must be done with d_getrec.  If you know the
  63. structure of the dbf records at compile time, it would be more efficient to
  64. create a pointer to a structure which matches the content of the record.
  65. This pointer could then be pointed to the record in memory.
  66.  
  67. dBASE III stores all records in ascii format.  Character fields are stored
  68. padded with spaces ('\x20' rather than nulls).  Numbers are right justified
  69. within their field and again padded with spaces.  Logical fields are single
  70. bytes containing T,t,y,F,f,n.
  71.  
  72. The d_blank function fills the record in memory with blanks.  This is
  73. usefull for appending blank records and making sure the record is blank
  74. before filling with new data.
  75.  
  76. d_addrec writes the data contained in the memory record to the end of the dbf
  77. file.  d_close updates the "date of last update" and number of records
  78. information contained in the dbf file header, and appends a end of file marker
  79. to the end of the file.  Any file which has been changed with d_putrec or
  80. d_addrec should always be closed with d_close.  d_close also deallocates memory
  81. which was allocated by d_open.  You must deallocate space for the DBF structure.
  82.  
  83. The structure of dBASE III files is as follows:
  84.  
  85. dBASE III DATABASE FILE HEADER:
  86. +---------+-------------------+---------------------------------+
  87. |  BYTE   |     CONTENTS      |          MEANING                |
  88. +---------+-------------------+---------------------------------+
  89. |  0      |  1 byte           | dBASE III version number        |
  90. |         |                   |  (03H without a .DBT file)      |
  91. |         |                   |  (83H with a .DBT file)         |
  92. +---------+-------------------+---------------------------------+
  93. |  1-3    |  3 bytes          | date of last update             |
  94. |         |                   |  (YY MM DD) in binary format    |
  95. +---------+-------------------+---------------------------------+
  96. |  4-7    |  32 bit number    | number of records in data file  |
  97. +---------+-------------------+---------------------------------+
  98. |  8-9    |  16 bit number    | length of header structure      |
  99. +---------+-------------------+---------------------------------+
  100. |  10-11  |  16 bit number    | length of the record            |
  101. +---------+-------------------+---------------------------------+
  102. |  12-31  |  20 bytes         | reserved bytes (version 1.00)   |
  103. +---------+-------------------+---------------------------------+
  104. |  32-n   |  32 bytes each    | field descriptor array          |
  105. |         |                   |  (see below)                    | --+
  106. +---------+-------------------+---------------------------------+   |
  107. |  n+1    |  1 byte           | 0DH as the field terminator     |   |
  108. +---------+-------------------+---------------------------------+   |
  109. |                                                                   |
  110. |                                                                   |
  111. A FIELD DESCRIPTOR:      <------------------------------------------+
  112. +---------+-------------------+---------------------------------+
  113. |  BYTE   |     CONTENTS      |          MEANING                |
  114. +---------+-------------------+---------------------------------+
  115. |  0-10   |  11 bytes         | field name in ASCII zero-filled |
  116. +---------+-------------------+---------------------------------+
  117. |  11     |  1 byte           | field type in ASCII             |
  118. |         |                   |  (C N L D or M)                 |
  119. +---------+-------------------+---------------------------------+
  120. |  12-15  |  32 bit number    | field data address              |
  121. |         |                   |  (address is set in memory)     |
  122. +---------+-------------------+---------------------------------+
  123. |  16     |  1 byte           | field length in binary          |
  124. +---------+-------------------+---------------------------------+
  125. |  17     |  1 byte           | field decimal count in binary   |
  126. +---------+-------------------+--------------------------------
  127. |  18-31  |  14 bytes         | reserved bytes (version 1.00)   |
  128. +---------+-------------------+---------------------------------+
  129. The data records are layed out as follows:
  130. 1. Data records are preceeded by one byte that is a
  131. space (20H) if the record is not deleted and an
  132. asterisk (2AH) if it is deleted.
  133. 2. Data fields are packed into records with no field
  134. separators or record terminators.
  135. 3. Data types are stored in ASCII format as follows:
  136. DATA TYPE      DATA RECORD STORAGE
  137. ---------      --------------------------------------------
  138. Character      (ASCII characters)
  139. Numeric        - . 0 1 2 3 4 5 6 7 8 9
  140. Logical        ? Y y N n T t F f  (? when not initialized)
  141. Memo           (10 digits representing a .DBT block number)
  142. Date           (8 digits in YYYYMMDD format, such as
  143. 19840704 for July 4, 1984)
  144.  
  145. This information came directly from the Ashton-Tate Forum. It can also be
  146. found in the Advanced Programmer's Guide available from Ashton-Tate.
  147.  
  148. One slight difference occurs between files created by dBASE III and those
  149. created by dBASE III Plus.  In the earlier files, there is an ASCII NUL
  150. character between the $0D end of header indicator and the start of the
  151. data. This NUL is no longer present in Plus, making a Plus header one byte
  152. smaller than an identically structured III file.  The functions included
  153. here will work with either version of dBASE III and writes files which may
  154. be used by either.
  155.  
  156. The field record array which is created by d_open is a memory image of the
  157. field description array contained in the dbf file.  The "field data
  158. address" is evidently filled in by dBASE when the file is opened with a use
  159. command and points to the memory location where the field is stored in
  160. memory.  d_open does the same thing.
  161.  
  162. The field description array and portions of the DBF structure is filled by
  163. d_open with the fread function.  The portion of the DBF structure which is
  164. filled this way is marked, do not change.  Also do not change the
  165. FIELD_RECORD structure.  Finally do not use the -a switch to compile any
  166. program which includes dbf.h so that these structures will be filled
  167. correctly.
  168.  
  169. Two programs are included as examples:
  170.  
  171.     dbstat - prints statistics about a dbf file
  172.     listdb - prints the contents of a dbf file
  173.     dbcopy - copies a dbf file
  174.